Stripe API Design Decisions

Until now, we have understood the requirements of Stripe and its importance in the payment system. In this lesson, we will learn about Stripe and discuss the interaction of various micro-services that make it operational. Further, we will decide on some important technical aspects such as API architectural styles for interaction with different entities, communication protocols, and data formats for exchanging data with clients and backend services.

Let's start with the internal services of Stripe by presenting its abstract architecture.

Design overview#

Stripe provides a good number of services to their customers that handle each aspect of the payment process. We will focus on prominent services that include customer, session, invoices, charges, refunds, balance, and payout services, as shown in the figure below:

The client could be a customer or merchant whose requests are passed through the API gateway and directed to a relevant service. Each service shown in the above figure is described below:

• Customer service: This service performs the operations relevant to a customer's data—for example, creating, updating, deleting, retrieving, and storing their payment details.

• Session service: The session service is responsible for maintaining the session during the payment process. This service mainly handles customer data, such as ID, name, and other relevant credentials, during the payment process.

• Invoices service: This performs the task of generating statements of funds that the customer is paying.

• Charges service: This service is responsible for charging a credit or debit card. An important role of this service is to assign a unique ID to each charge operation.

• Refunds service: Sometimes, a customer cancels their order after payment or requests a refund. This service is responsible for reversing the funds to the customer's credit or debit card after the verification by the concerned authority/merchant.

• Balance service:  This is responsible for managing the balance in the merchant's Stripe account. Merchants can get money transferred to their bank accounts through payouts.). The balance can be increased or decreased based on the cash inflow and outflow, respectively. The transaction may take up to several days to be cleared due to multiple parties being involved in the process. Therefore, the balance server is an explicit service that keeps track of each transaction and its corresponding status.

• Payouts service: This service manages all the operations of payouts—for example, when a merchant receives or initiates a payout to their bank account.

• Pub-sub service: This service is responsible for directing the communication between other services. It also allows services to scale through asynchronous communication.

Note: We can deduce from the explanations above that most of the services will require interaction with the cards networks. We have talked about this in more detail in the “Stripe Interaction with Cards Network” lesson.

Workflow#

Let's discuss the workflow of Stripe according to the services mentioned above:

When a customer aims to purchase an item via a credit or debit card, the session service establishes a session and maintains it throughout the payment process. To process a purchase, the invoices service provides a bill to the customer, which is paid via the charges service. Sometimes a customer may request a refund for any reason, and these are handled via the refunds service.

Similarly, the balance service manages and keeps track of the merchant's balance—for example, upon purchase from the customer, it is increased, while upon a refund, the amount is deducted accordingly. Meanwhile, the merchant can transfer a specific balance amount to their bank accounts via the payouts service.

We have seen the design and workflow of Stripe; now, let's focus on the important technical considerations required to design the Stripe API.

Design considerations#

When it comes to the interaction, the questions that arise are how the client communicates with the API gateway and what principles need to be followed while exchanging data between different interacting components. To answer such questions, we will discuss the API architecture styles, protocols, and data formats that govern the communication between client, API gateway, and backend services in the following sections.s

API architecture styles#

Primarily, there are two types of interactions taking place in the workflow we presented earlier. Let's explain and decide on an API architecture style for each interaction.

Client-to-API gateway#

If we look at the fundamental usage of Stripe, we find that it is integrated into third-party applications where customers initiate the payment process after entering their card details. The customers as well as merchants request via an API gateway to access various resources—for example, checking their account balances, retrieving invoices, or viewing transaction information. In essence, the interaction with the API gateway occurs in a request-response paradigm to access multiple resources and perform CRUD operations on them. As a result, we opt for the REST API architecture style since it is a natural fit for such a use case.

API gateway-to-backend services#

When the API gateway receives a request, it is parsed and transformed into a suitable format to fetch or post data to the backend servers. A single request might need data from multiple endpoints because we are targeting multiple interdependent services via the API gateway. The charges service performs the transfer of funds on successful completion of the transaction, whereas the customer service updates the merchant’s account. At the same time, the session service is actively maintaining the user session. So here, we need a data federation strategy to unify data from multiple sources, which can be easily achieved by incorporating GraphQL between the API gateway and backend servers.

Data formats#

Stripe works with critical data; therefore, we need to allow restricted access to it. For this reason, the server accepts data in the x-www-form-urlencoded format. This format not only supports textual data but avoids the interchange of data via large files that could be potentially harmful. It also avoids using binary data and control characters, which improves protection against various security vulnerabilities. Also, it is convenient to perform validation and sanitization of x-www-form-urlencoded data. Furthermore, URL-encoded form data is a default choice for sending textual or ASCII data.

A good option for the response from the server is a JSON-encoded format. This is because this format is widely adopted in client-side applications due to its lightweight and easy-to-parse nature.

Meanwhile, JSON fits well into the GraphQL paradigm as the data format of choice. It is a suitable option for API and backend services. Another reason for choosing JSON is that the Stripe backend services frequently talk to third-party services, so using a compact and human-readable format makes sense.

Note: Our API will use the  x-www-form-urlencoded data in the request to the API, while the response will use the JSON data.

Protocols#

In communication with Stripe, we pass on critical information that has to be securely transmitted to the API gateway and onward. For this purpose, it is recommended to use TLS 1.3, which significantly reduces the risk of exposing customer data and avoids a man-in-the-middle (MITM) attack. Since HTTP/2.0 is designed to work best with TLS 1.3, it becomes a suitable option to adopt.

Moreover, HTTP/2.0 is backward compatible, so the consumers of the API having other HTTP versions can also use our API. Hence, HTTP/2.0 benefits us by making our API more secure without affecting the users' experience.

Note: The payment card industry (PCI) security standards recommend the use of TLS 1.2 or higher for businesses that exchange credit or debit card details directly with an API.

In the next lesson, let's start with the Stripe API model in light of the technical decisions we made in this lesson.